<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libcoap: coap_handler(3)</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">libcoap<span id="projectnumber">&#160;4.2.0</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('man_coap_handler.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">coap_handler(3)</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>coap_handler</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /></head><body><div xml:lang="en" class="refentry" lang="en"><a id="id1337"></a><div class="titlepage"></div><div class="refnamediv"><h2>NAME</h2><p>coap_handler, coap_register_handler, coap_register_response_handler, coap_register_nack_handler, coap_register_ping_handler, coap_register_pong_handler, coap_register_event_handler — work with CoAP handlers</p></div><div class="refsynopsisdiv"><a id="_synopsis"></a><h2>SYNOPSIS</h2><p><span class="strong"><strong>#include &lt;coap2/coap.h&gt;</strong></span></p><p><span class="strong"><strong>void coap_register_handler(coap_resource_t *<span class="emphasis"><em>resource</em></span>, unsigned char
<span class="emphasis"><em>method</em></span>, coap_method_handler_t <span class="emphasis"><em>handler</em></span>);</strong></span></p><p><span class="strong"><strong>void coap_register_response_handler(coap_context_t *<span class="emphasis"><em>context</em></span>,
coap_response_handler_t <span class="emphasis"><em>handler</em></span>)</strong></span>;</p><p><span class="strong"><strong>void coap_register_nack_handler(coap_context_t *<span class="emphasis"><em>context</em></span>,
coap_nack_handler_t <span class="emphasis"><em>handler</em></span>)</strong></span>;</p><p><span class="strong"><strong>void coap_register_ping_handler(coap_context_t *<span class="emphasis"><em>context</em></span>,
coap_ping_handler_t <span class="emphasis"><em>handler</em></span>)</strong></span>;</p><p><span class="strong"><strong>void coap_register_pong_handler(coap_context_t *<span class="emphasis"><em>context</em></span>,
coap_pong_handler_t <span class="emphasis"><em>handler</em></span>)</strong></span>;</p><p><span class="strong"><strong>void coap_register_event_handler(coap_context_t *<span class="emphasis"><em>context</em></span>,
coap_event_handler_t <span class="emphasis"><em>handler</em></span>)</strong></span>;</p><p>Link with <span class="strong"><strong>-lcoap-2</strong></span>, <span class="strong"><strong>-lcoap-2-gnutls</strong></span>,
<span class="strong"><strong>-lcoap-2-openssl</strong></span> or
<span class="strong"><strong>-lcoap-2-tinydtls</strong></span> depending on your (D)TLS library
type.</p></div><div class="refsect1"><a id="_description"></a><h2>DESCRIPTION</h2><p>The <span class="strong"><strong>coap_register_handler</strong></span>() function registers a callback handler <span class="emphasis"><em>handler</em></span>
that is called when there is a URI match against the <span class="emphasis"><em>resource</em></span> and there is
a <span class="emphasis"><em>method</em></span> (e.g. PUT, POST etc.) match. <span class="emphasis"><em>method</em></span> can be one of the following.</p><pre class="screen">COAP_REQUEST_GET
COAP_REQUEST_POST
COAP_REQUEST_PUT
COAP_REQUEST_DELETE
COAP_REQUEST_FETCH
COAP_REQUEST_PATCH
COAP_REQUEST_IPATCH</pre><p>The handler function prototype is defined as:</p><pre class="programlisting">typedef void (*coap_method_handler_t)(coap_context_t *context,
                                      coap_resource_t *resource,
                                      coap_session_t *session,
                                      coap_pdu_t *incoming_pdu,
                                      coap_string_t *token,
                                      coap_string_t *query,
                                      coap_pdu_t *response_pdu);</pre><p>The <span class="strong"><strong>coap_register_response_handler</strong></span>() function defines a request’s response
<span class="emphasis"><em>handler</em></span> for traffic associated with the <span class="emphasis"><em>context</em></span>.  The application can use
this for handling any response packets, including sending a RST packet if this
response was unexpected.  If <span class="emphasis"><em>handler</em></span> is NULL, then the handler is
de-registered.</p><p>The handler function prototype is defined as:</p><pre class="programlisting">typedef void (*coap_response_handler_t)(coap_context_t *context,
                                        coap_session_t *session,
                                        coap_pdu_t *sent,
                                        coap_pdu_t *received,
                                        const coap_tid_t id);</pre><p>The <span class="strong"><strong>coap_register_nack_handler</strong></span>() function defines a request’s negative
response <span class="emphasis"><em>handler</em></span> for traffic associated with the <span class="emphasis"><em>context</em></span>.
If <span class="emphasis"><em>handler</em></span> is NULL, then the handler is de-registered.</p><p>The handler function prototype is defined as:</p><pre class="programlisting">typedef void (*coap_nack_handler_t)(coap_context_t *context,
                                    coap_session_t *session,
                                    coap_pdu_t *sent,
                                    coap_nack_reason_t reason,
                                    const coap_tid_t id);</pre><p>The <span class="strong"><strong>coap_register_ping_handler</strong></span>() function defines a <span class="emphasis"><em>handler</em></span> for tracking
CoAP ping traffic associated with the <span class="emphasis"><em>context</em></span>. If <span class="emphasis"><em>handler</em></span> is NULL, then
the handler is de-registered.</p><p>The handler function prototype is defined as:</p><pre class="programlisting">typedef void (*coap_ping_handler_t)(coap_context_t *context,
                                    coap_session_t *session,
                                    coap_pdu_t *received,
                                    const coap_tid_t id);</pre><p>The <span class="strong"><strong>coap_register_pong_handler</strong></span>() function defines a <span class="emphasis"><em>handler</em></span> for tracking
CoAP TCP ping response traffic associated with the <span class="emphasis"><em>context</em></span>.
If <span class="emphasis"><em>handler</em></span> is NULL, then the handler is de-registered.</p><p>The handler function prototype is defined as:</p><pre class="programlisting">typedef void (*coap_pong_handler_t)(coap_context_t *context,
                                    coap_session_t *session,
                                    coap_pdu_t *received,
                                    const coap_tid_t id);</pre><p>The <span class="strong"><strong>coap_register_event_handler</strong></span>() function defines a <span class="emphasis"><em>handler</em></span> for tracking
(D)TLS events associated with the <span class="emphasis"><em>context</em></span>. If <span class="emphasis"><em>handler</em></span> is NULL, then
the handler is de-registered.</p><p>The handler function prototype is defined as:</p><pre class="programlisting">typedef void (*coap_event_handler_t)(coap_context_t *context,
                                     coap_event_t event,
                                     coap_session_t *session);</pre><p>Events can be one of the following</p><pre class="screen">/**
 * (D)TLS events for COAP_PROTO_DTLS and COAP_PROTO_TLS
 */
COAP_EVENT_DTLS_CLOSED        0x0000
COAP_EVENT_DTLS_CONNECTED     0x01DE
COAP_EVENT_DTLS_RENEGOTIATE   0x01DF
COAP_EVENT_DTLS_ERROR         0x0200
/**
 * TCP events for COAP_PROTO_TCP and COAP_PROTO_TLS
 */
COAP_EVENT_TCP_CONNECTED      0x1001
COAP_EVENT_TCP_CLOSED         0x1002
COAP_EVENT_TCP_FAILED         0x1003
/**
 * CSM exchange events for reliable protocols only
 */
COAP_EVENT_SESSION_CONNECTED  0x2001
COAP_EVENT_SESSION_CLOSED     0x2002
COAP_EVENT_SESSION_FAILED     0x2003</pre></div><div class="refsect1"><a id="_examples"></a><h2>EXAMPLES</h2><p><span class="strong"><strong>GET Resource Callback Handler</strong></span></p><pre class="programlisting">#include &lt;coap2/coap.h&gt;

void
hnd_get_time(coap_context_t *context, coap_resource_t *resource,
coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
coap_string_t *query, coap_pdu_t *response) {

  unsigned char buf[40];
  size_t len;
  time_t now;

  /* ... Additional analysis code for resource, request pdu etc.  ... */

  /* After analysis, generate a suitable response */

  /* Note that token, if set, is already in the response pdu */

  now = time(NULL);

  if (query != NULL &amp;&amp; coap_string_equal(query, coap_make_str_const("secs"))) {
    /* Output secs since Jan 1 1970 */
    len = snprintf((char *)buf, sizeof(buf), "%lu", now);
  }
  else {
    /* Output human-readable time */
    struct tm *tmp;
    tmp = gmtime(&amp;now);
    if (!tmp) {
      /* If 'now' is not valid */
      response-&gt;code = COAP_RESPONSE_CODE(404);
      return;
    }
    len = strftime((char *)buf, sizeof(buf), "%b %d %H:%M:%S", tmp);
  }
  /*
   * Invoke coap_add_data_blocked_response() to do all the hard work.
   *
   * Define the format - COAP_MEDIATYPE_TEXT_PLAIN - to add in
   * Define how long this response is valid for (secs) - 1 - to add in.
   *
   * OBSERVE Option added internally if needed within the function
   * BLOCK2 Option added internally if output too large
   * ETAG Option added internally
   */
  coap_add_data_blocked_response(resource, session, request, response, token,
                                 COAP_MEDIATYPE_TEXT_PLAIN, 1,
                                 len,
                                 buf);

  /*
   * As resource-&gt;code has been updated in coap_add_data_blocked_response(),
   * the response pdu will be transmitted by the underlying library.
   */

}</pre><p><span class="strong"><strong>Packet Response Handler</strong></span></p><pre class="programlisting">#include &lt;coap2/coap.h&gt;

static void
response_handler(coap_context_t *ctx, coap_session_t *session,
coap_pdu_t *sent, coap_pdu_t *received, const coap_tid_t id) {

  coap_pdu_t *pdu = NULL;
  coap_opt_t *block_opt;
  coap_opt_iterator_t opt_iter;
  unsigned char buf[4];
  size_t len;
  unsigned char *databuf;
  coap_tid_t tid;

  /* check if this is a response to our original request */
  if (!check_token(received)) {
    /* drop if this was just some message, or send RST in case of notification */
    if (!sent &amp;&amp; (received-&gt;type == COAP_MESSAGE_CON ||
                  received-&gt;type == COAP_MESSAGE_NON))
      coap_send_rst(session, received);
    return;
  }

  if (received-&gt;type == COAP_MESSAGE_RST) {
    info("got RST\n");
    return;
  }

  /* Output the received data, if any */
  if (COAP_RESPONSE_CLASS(received-&gt;code) == 2) {
    /* Additional code to deal with the response */

  }
  return;

}</pre></div><div class="refsect1"><a id="_see_also"></a><h2>SEE ALSO</h2><p><a href="man_coap_resource.html" target="_self"><span class="strong"><strong>coap_resource</strong></span>(3)</a></p></div><div class="refsect1"><a id="_further_information"></a><h2>FURTHER INFORMATION</h2><p>See "RFC7252: The Constrained Application Protocol (CoAP)" for further
information.</p></div><div class="refsect1"><a id="_bugs"></a><h2>BUGS</h2><p>Please report bugs on the mailing list for libcoap:
<a class="ulink" href="mailto:libcoap-developers@lists.sourceforge.net" target="_top">libcoap-developers@lists.sourceforge.net</a></p></div><div class="refsect1"><a id="_authors"></a><h2>AUTHORS</h2><p>The libcoap project &lt;<a class="ulink" href="mailto:libcoap-developers@lists.sourceforge.net" target="_top">libcoap-developers@lists.sourceforge.net</a>&gt;</p></div></div></body></html> coap_handler(3)</p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Fri Dec 27 2024 09:57:44 for libcoap by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.8 </li>
  </ul>
</div>
</body>
</html>
